I wonder if it's worth re-evaluating some of these deprecated instance methods now that we've agreed to use the static methods on Context for things like attach/detach and treat Context as its own immutable propagation context.

When I was reading through the examples above, I found things like this a bit confusing/daunting:

  final rootToken = Context.attach(
      contextWithSpan(Context.current, tracer.startSpan('root-1')..end()));

As a consumer, I might wonder when I should use a static method like Context.attach versus a top-level helper function like contextWithSpan. That example also uses contextWithSpan(Context.current, ...) twice, which makes me wonder – if that's a common pattern, is there a way we can streamline it and avoid the user needing to take a roundabout way to create a new context from the current context with a given span?

I feel like OTEL really needs a major to clean out the deprecations. It's gotten pretty bad and difficult to think through given the quantity of deprecated code.

Context is its own immutable propagation context as it is implemented now. I would like to refrain from muddying its APIs with unnecessary methods about spans. Spans need context, context doesn't need spans. So stuff like contextWithSpan() or spanFromContext() are cross-cutting APIs vs the static methods that pertain to context alone.

I agree with you that having the cross-cutting APIs as top-level functions while the context specific APIs are static methods on the Context class is confusing, especially without keeping this distinction in mind. But if we want to colocate the functions, I'd opt for moving the context specific static APIs out of the class before moving cross-cutting APIs into the class.

I think there are common patterns that can be a little clunky, like you've demonstrated. In my option:

1. It's demonstrating what is happening, and how it works. No need to guess, your intuition will suffice
2. Additional APIs would require maintaining additional APIs.
3. If consumers want something stream lined, I think it's reasonable to expect the consumer to define helper functions.
   • I might change my opinion once Dart 2 support is thrown out. Defining functions that return a record as a tuple of context and span, mimicking golang APIs, would be clean. But I would not want to add a new type or update an interface to support this behavior.

👍 that's helpful, thanks Blake!

Not a blocker-comment, just clarifying my understanding and if correct, want us to be aware:

Are we deviating from the OTEL spec by deprecating the context manager? It seems like the attach and detach context approach is analogous to setting the active context.

Those links are not to the spec, but to the JavaScript implementation of the spec. The context spec is this document: https://opentelemetry.io/docs/specs/otel/context/. Getting a global, attaching, and detaching context are mentioned in the optional global operations section

To touch on context manager specifically:

• It isn't required spec, only how the JavaScript implementation decided to organize themselves.
• Other languages do not have a context manager.
• I believe the main reason for the context manager abstraction is that Zones are not standard library for JavaScript. So the context manager is a type of inversion of control. The consumer can decide if they want to build their bundle with zones or not. And ofc this is not relevant to Dart since Zones are a part of the standard library.